🏠 API de UsuarioEnderecos - Documentação Completa

📋 Visão Geral

A API de UsuarioEnderecos é responsável por toda a gestão de endereços dos usuários no sistema CordenaAi, incluindo cadastro, atualização, consulta e exclusão de endereços residenciais, comerciais e outros tipos. Esta API fornece a base para localização e contato dos usuários, permitindo a organização de dados geográficos e facilitando a comunicação e logística.

🎯 Endpoints Disponíveis

🏠 UsuarioEnderecos - Gestão de Endereços de Usuários

1. GET /api/UsuarioEnderecos/usuario/{usuarioId}

Listar Endereços por Usuário

2. GET /api/UsuarioEnderecos/{id}

Obter Endereço por ID

3. POST /api/UsuarioEnderecos

Criar Endereço

4. PUT /api/UsuarioEnderecos/{id}

Atualizar Endereço

5. DELETE /api/UsuarioEnderecos/{id}

Excluir Endereço

🔧 Modelo de Dados

UsuarioEndereco

CreateDto (Criação)

{
  "usuarioId": "string",
  "enderecoResponsavelId": "string",
  "cep": "string",
  "endereco": "string",
  "numero": "string",
  "complemento": "string",
  "bairro": "string",
  "cidade": "string",
  "estado": "string",
  "tipo": 1
}

UpdateDto (Atualização)

{
  "usuarioId": "string",
  "enderecoResponsavelId": "string",
  "cep": "string",
  "endereco": "string",
  "numero": "string",
  "complemento": "string",
  "bairro": "string",
  "cidade": "string",
  "estado": "string",
  "tipo": 1
}

ReadDto (Consulta)

{
  "id": 1,
  "usuarioId": "string",
  "usuarioNome": "string",
  "enderecoResponsavelId": "string",
  "enderecoResponsavelNome": "string",
  "cep": "01234-567",
  "endereco": "Rua das Flores",
  "numero": "123",
  "complemento": "Apto 45",
  "bairro": "Centro",
  "cidade": "São Paulo",
  "estado": "SP",
  "tipo": 1,
  "dataCadastro": "2025-01-15T10:30:00Z",
  "dataAtualizacao": "2025-01-15T10:30:00Z"
}

Tipos de Endereço

{
  "TipoEndereco": {
    "Residencial": 1,
    "Comercial": 2,
    "Outro": 3
  }
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Cadastro de Endereço Residencial

POST /api/UsuarioEnderecos
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-guid-here",
  "enderecoResponsavelId": "responsible-guid-here",
  "cep": "01234-567",
  "endereco": "Rua das Flores",
  "numero": "123",
  "complemento": "Apto 45",
  "bairro": "Centro",
  "cidade": "São Paulo",
  "estado": "SP",
  "tipo": 1
}

2. Consulta de Endereços por Usuário

GET /api/UsuarioEnderecos/usuario/user-guid-here
Authorization: Bearer {token}

3. Atualização de Endereço

PUT /api/UsuarioEnderecos/1
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-guid-here",
  "enderecoResponsavelId": "responsible-guid-here",
  "cep": "01234-567",
  "endereco": "Rua das Flores",
  "numero": "123",
  "complemento": "Apto 45",
  "bairro": "Centro",
  "cidade": "São Paulo",
  "estado": "SP",
  "tipo": 1
}

4. Consulta de Endereço Específico

GET /api/UsuarioEnderecos/1
Authorization: Bearer {token}

5. Exclusão de Endereço

DELETE /api/UsuarioEnderecos/1
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Validações Opcionais

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo Completo de Cadastro de Endereço

  1. Validar CEP via serviço externo
  2. Criar endereço via POST /api/UsuarioEnderecos
  3. Verificar endereço criado via GET /api/UsuarioEnderecos/{id}
  4. Listar endereços do usuário via GET /api/UsuarioEnderecos/usuario/{usuarioId}
  5. Atualizar se necessário via PUT /api/UsuarioEnderecos/{id}

Fluxo de Gestão por Responsável

  1. Listar endereços via GET /api/UsuarioEnderecos/usuario/{usuarioId}
  2. Filtrar por tipo no frontend
  3. Editar endereço via PUT /api/UsuarioEnderecos/{id}
  4. Excluir endereço obsoleto via DELETE /api/UsuarioEnderecos/{id}
  5. Verificar alterações via GET /api/UsuarioEnderecos/{id}

Fluxo de Validação de CEP

  1. Capturar CEP no formulário
  2. Validar formato no frontend
  3. Consultar serviço de CEP (opcional)
  4. Preencher campos automaticamente
  5. Salvar endereço via POST /api/UsuarioEnderecos

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi